MCS-1.6.1000.1 Web-Socket API

Provides a request-response API for local web-socket clients to interact with MyID components.

Table of Contents

• Changelog
• Pre-Requisites
• API Notes
• Applets
  • SelectCard
  • LoginWithCard
  • CaptureFingerprints
  • CaptureFacialBioWithMic
  • ScanDocument
  • ModifyImage
• Workflows
  • StartWithToken
• Configuration
  • GetVersion
  • SetLanguage

Changelog

• 1.6.1000.1
  • First public release

Pre-Requisites

To use this API, the following are required:

• MyID Client Service 1.6.1000.1 (MCS-1.6.1000.1).
• MyID 12.3.0 or higher.

Some Applets require additional components be installed:

• CaptureFingerprints
  • The current integration patch corresponding to the fingerprint capture device-type to be used must be installed; for example, the Secugen patch must be installed to use a supported Secugen device. Consult the the MyID documentation for more details.
  • Without the corresponding patch, MCS will be unable to detect the fingerprint capture device.
• CaptureFacialBioWithMic
  • The current Aware PreFace patch must be installed. Consult the MyID Documentation for more details.
  • Without the PreFace patch, the MyID Image Capture window will display an error on launch.
• ScanDocument
  • To use scanners via the TWAIN interface, the current x86 TWAIN DSM patch must be installed. Consult the MyID Documentation for more details.
    • This is not required if you only intend to use scanners via the WIA interface.

Workflow invocation requires the installation and configuration of additional MyID client(s), depending on your use-case:

• StartWithToken
  • StartWithToken can launch workflows with MyID Desktop (DSK) and/or MyID Self-Service Application (SSA).
    • For DSK workflows, DSK-3.12.1000.1 or higher is required.
    • For SSA workflows, SSP-3.12.1000.1 or higher is required.
    • For details on specific client/server support for particular operations, see: Supported Operations.
  • DSK/SSA must be configured to connect to the same MyID server as MCS.
  • If DSK/SSA is not installed in the default location, the path to the installation must be configured in the MCS configuration file. Within the <appSettings> node, add the following according to the client you are configuring, replacing the value (default path shown in examples) with the path to the client's installation directory:
    • MyID Desktop (DSK):

      <add key="DskPath" value="C:\Program Files (x86)\Intercede\MyIDDesktop">
      

    • MyID Self-Service Application (SSA):

      <add key="SsaPath" value="C:\Program Files (x86)\Intercede\MyIDApp\Self Service Application">
      

API Notes

• MCS hosts a local web-socket server to provide the API. By default, this is available at ws://localhost:8081 - if you have configured MyID/MCS to use a different port, substitute 8081 for your configured port number.

  Basic WebSocket Example

  // Request to call GetVersion
  const request = 
  {
    Type: "Configuration", 
    Method: "GetVersion",
    ID: "Example"
  }
  
  // Connect to MCS
  const socket = new WebSocket("ws://localhost:8081");
  
  // Send message to MCS when web-socket connects
  socket.onopen = function(e) 
  {
    socket.send(JSON.stringify(request));
  }
  
  // Handle response in `onmessage` event
  socket.onmessage = function(event) 
  {
    const response = JSON.parse(event.Data);
    if(response.ID == "Example")
    {
      // ID matches request; expected response.
      if(response.Success)  
      {
        alert(`MCS is version: {response.Version}`);
      } 
      else 
      {
        alert("GetVersion call failed");
      }
    } 
    else 
    {
      // ID doesn't match request; not the response we want.
    }
  }
  

• MCS only allows API connections from the local machine.

• MCS will, by default, reject API connections where the Origin header is unrecognised. To use the API, the origin of your caller must be added to the AccessControlAllowOrigin configuration or DisableAccessControl must be set to true.

  • ❗ Note: If DisableAccessControl is set to true, MCS will accept API connections from any origin.

• MCS can only service a single request at a time

  • If multiple requests are sent on the same web-socket connection they are queued and executed in the order they were received.
  • If a request on a new web-socket connection is made while a request is ongoing on another connection, it will immediately return a failure response.

• Requests are made by providing a 'header' containing a Type and Method to invoke, an optional ID, and an array of arguments (Args) where the method being called demands it.

  • When an ID is provided in the request header, MCS includes it in the response - this can make it simpler to pair API responses to their corresponding requests. MCS does not perform any 'uniqueness' checks on IDs, simply echoing the provided value in the response.
  • ❗ Note: Arguments are positional and must be presented in the documented order.

  Example request without arguments or ID. The response will not include an ID.

  {
      "Type": "SomeType",
      "Method": "SomeMethod"
  }
  

  Example request with ID, and without arguments. "SomeIdValue" will be the ID of the response.

  {
      "Type": "SomeType",
      "ID": "SomeIdValue",
      "Method": "SomeMethod"
  }
  

  Example request with arguments, and without ID. The response will not include an ID.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

  Example request with arguments and ID. "SomeIdValue" will be the ID of the response.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "ID": "SomeIdValue",
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

Applets

MCS provides GUI applets to perform the following functions:

• Select a security device (SelectCard)
• Login to MyID with a security device (LoginWithCard)
• Capture fingerprints (CaptureFingerprints)
• Capture facial biometrics (CaptureFacialBioWithMic)
• Scan a document (ScanDocument)
• Crop an image and adjust its brightness/contrast (ModifyImage)

SelectCard

Presents the operator with a device-picker, and returns the details of the selected security device.

Input

Header

Arguments

None

Example Input

{
  "Type": "Applet",
  "Method": "SelectCard"
}

Output

Example Output

{
    "Success": true,
    "SerialNumber": "OBERTHUR0123456789",
    "DeviceTypeName": "Oberthur ID-One PIV",
    "ChipType": "Oberthur ID-One PIV",
    "DeviceVersion": "02.34"
}

LoginWithCard

Presents the operator with a device-picker, then allows the operator to login to MyID with the selected device and return the session GUID.

Input

Header

Example input

{
    "Type": "Applet",
    "Method": "LoginWithCard"
}

Arguments

None

Output

Example output

{
    "Success": true,
    "SessionGuid": "-7850638,6EDEA9BC-BBAB-4E6C-9850-6035CA300BD2"
}

CaptureFingerprints

Presents the operator with a fingerprint capture dialog containing a list of fingers to be captured, and immediately starts scanning for the first impression. The captured prints are returned to the caller in INCITS-378 format as part of a JSON block that includes additional metadata and is formatted for the MyID Core API.

❗ Note: as per the pre-requisites, this applet requires additional components corresponding to your fingerprint capture device-type be installed.

There are two different modes for the CaptureFingerprints API:

Specific-Finger Capture

• Allows >=1 fingers to be specified for capture.
• MyID uses this mode to perform enrolments, where captures are to be added to the MyID records.

Unspecified Single-Finger Capture

• A single, unspecified finger is captured without restriction.
• MyID uses this mode for verification, where the captured print is compared against the prints MyID has on record.

Input

Header

Arguments

Finger IDs

Fingerprint Capture Device-Types

Example specific-finger capture input

{
    "Type": "Applet",
    "Method": "CaptureFingerprints",
    "Args": 
    {
        "FingersToCapture": "RT;RI",
        "CaptureDeviceType": "Secugen"
    }
}

Example unspecified single-finger capture input

{
    "Type": "Applet",
    "Method": "CaptureFingerprints",
    "Args": 
    {
        "FingersToCapture": "ANY",
        "CaptureDeviceType": "Secugen"
    }
}

Output

Example specific-finger capture output

{
  "Success": true,
  "fingers": {
    "rt": {
        "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
        "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
        },
        "quality": "97",
        "status": "P"
    },
    "ri": {
        "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
        "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
        },
        "quality": "96",
        "status": "P"
    }
  }
}

Example unspecified single-finger capture output

{
  "Success": true,
  "fingers": {
    "any": {
      "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
      "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
      },
      "quality": "97",
      "status": "P"
    }
  }
}

CaptureFacialBioWithMic

Presents the user with the MyID Image Capture (MIC) tool, which utilises Aware PreFace to capture facial biometrics according to pre-defined compliance profiles. In addition to the INCITS-385 biometric data, MIC also provides the captured image as a standard JPEG for use in more conventional scenarios (e.g. displaying in a browser, or printing onto a smartcard).

❗ Note: as per the pre-requisites, this applet requires that the separate Aware PreFace components be installed.

Input

Header

Arguments

Hair Colour

These values correspond to those in the ANSI INCITS 385-2004 standard.

Eye Colour

These values correspond to those in the ANSI INCITS 385-2004 standard.

Gender

These values correspond to those in the ANSI INCITS 385-2004 standard.

Aware PreFace Profiles

MyID provides a default PIV Card Profile as part of installation, which can be found in <MyIDServerInstallPath>\rest.core\awareProfiles\core\AwareProfiles.json.

Example input

{
    "Type": "Applet",
    "Method": "CaptureFacialBioWithMic",
    "Args" :
    {
        "MustConformToProfile": true,
        "MaxOptimisationPasses": 3,
        "HairColour": 1,
        "EyeColour": 2,
        "Gender": 1,
        "Profiles": "Base64 Profile Data"
    }
}

Output

Example output

{
   "Success": true,
   "facial": {
      "template": {
         "format": "385",
         "data": "<INCITS 385 Data>"
      },
      "photo": {
         "mimetype": "image/jpeg",
         "data": "<Base64 JPEG>"
      },
      "bioDeviceId": "{DF6544E8-5F02-45c6-A599-C24BE4BC5A69}",
      "profile": "FIPS PIV Card",
      "compliant": true
   },
   "Error": null
}	

ScanDocument

Presents the operator with MyID Document Scanner (MDS), which can be used to scan documents using scanners supporting either the TWAIN or WIA interfaces. Where a scanner can only perform a single-page scan, multiple scans can be performed to capture additional pages. Basic control of the scanner is provided through the MDS UI when using TWAIN, and, where supported, the manufacturer's driver UI can be invoked when scanning. When using WIA, the standard Windows UI is used for scanning.

Scanned documents are returned as a single JPEG; where multiple pages have been captured they are arranged in a grid and combined into a single image.

❗ Note: as-per the pre-requisites, this applet requires the separate TWAIN component be installed to support scanners on the TWAIN interface. WIA can, where supported by the scanner, be used without additional components.

Input

Header

Arguments

None

Example input

{
  "Type": "Applet",
  "Method": "ScanDocument"
}

Output

Example output

{
  "Success": true,
  "Document": "<Base64 JPEG>"
}	

ModifyImage

Presents the operator with the MyID Image Editor (MIE), which can be used to perform simple image editing. Primarily a cropping tool, MIE can also be used to adjust brightness, contrast, and rotation of a supplied image.

❗ Note: Images are returned as JPEG regardless of their input type.

Input

Header

Arguments

None

The following describes the behaviour when the different crop options are provided:

Example input

{
    "Type": "Applet",
    "Method": "ModifyImage",
    "Args" :
    {
        "Base64Image": "<Base64 Image>",
        "Rotation": 90,
        "MaxHeight": 600,
        "MaxWidth": 400,
        "ValidateSize": true,
        "CropHeight": 0,
        "CropWidth": 0,
        "AspectRatio": "2:3",
        "JPEGCompressionRatio": 1
    }
}

Output

Example output

{
   "Success": true,
   "Base64Image": "<Base64 Image>",
   "Height": 300,
   "Width": 200,
   "MimeType": "image/jpeg"
}	

Workflows

MCS allows a caller to invoke MyID workflows in external clients via the web-socket API:

• Start a workflow with an OAuth token

StartWithToken

Uses an OAuth token to initialise a workflow in an external client, returning the result on completion. Initial authentication to MyID is provided via the token, which also contains metadata about the workflow to be started.

❗ Note: as-per the pre-requisites, this applet requires the separate MyID Desktop and/or the MyID Self-Service Application be installed.

MyID Desktop launched from StartWithToken:

MyID Self-Service Application launched from StartWithToken:

Supported Operations

Input

Header

Arguments

Example input (specific client; in this case, DSK)

{
  "Type": "Workflow",
  "Method": "StartWithToken",
  "Args" :
  {
    "Token": "token",
    "ClientData": "DSK",
    "OpId": "123"
  }
}

Example input (prefer DSK, but allow SSA if DSK is not available)

{
  "Type": "Workflow",
  "Method": "StartWithToken",
  "Args" :
  {
    "Token": "token",
    "ClientData": "DSK,SSA",
    "OpId": "123"
  }
}

Output

Workflow result-codes

Example success output

{
   "Success": true,
   "ErrorCode": "Success",
   "ExtendedErrorCode": null,
   "Message": null
}	

Example failure output

{
   "Success": false,
   "ErrorCode": "FailedWithError",
   "ExtendedErrorCode": "123",
   "Message": "Example error-message"
}

Configuration

MCS allows a caller to set configuration options and get client information via its web-socket API:

• Get the MCS product-version
• Set the language of Applets and external clients

GetVersion

Used to retrieve the MCS product-version so clients can determine the API level.

Input

Header

Arguments

None

Example input

{
  "Type": "Configuration",
  "Method": "GetVersion"
}

Output

Example output

{
   "Version": "MCS-1.6.1000.1",
   "Success": true
}	

SetLanguage

Allows a caller to specify a language to be used. This will apply to GUI applets and external clients (e.g. MyID Desktop) when they are invoked by MCS. If the requested language is already in use then this call has no effect.

❗ Note: This call causes MCS to request the translations for the specified language from the MyID server, but if the requested language is not installed then MyID will fall-back to the default language.

❗ Note: Language changes will not immediately be reflected in any already-open GUIs, but rather the next time the GUI is opened; for example, if a device-picker is on-screen then the language it uses will not immediately change, but the next time it is opened it will reflect the new language.

Input

Header

Arguments

Example input

{
  "Type": "Configuration",
  "Method": "SetLanguage",
  "Args":
  {
    "Language": "en-GB"
  }
}

Output

Example output

{
   "Success": true
}